Tangoe Telecom SOAP API

22.1.x
(0 reviews)

> Employee

addEmployee()

The method adds a new employee into the database using the provided fields from EmployeeDetails object. The result of the operation is an object represented by a code and a message that provides details about the success of the operation. Also the EIN of the new employee is returned as part of the response object. The employee is not created if another one with the same EIN already exists. The structure of the used objects may be observed in the appendix section of this document. The format of the request and response messages is the following:

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
   <soapenv:Header/>
   <soapenv:Body>
      <inv:AddEmployeeRequest>
         <inv:employee>
            <!--You may enter the following 15 items in any order-->
            <!--Optional:-->
            <inv:employeeID>?</inv:employeeID>
            <!--Optional:-->
            <inv:firstName>?</inv:firstName>
            <!--Optional:-->
            <inv:middleInitial>?</inv:middleInitial>
            <!--Optional:-->
            <inv:lastName>?</inv:lastName>
            <!--Optional:-->
            <inv:status>?</inv:status>
            <!--Optional:-->
            <inv:costCenterNo>?</inv:costCenterNo>
            <!--Optional:-->
            <inv:phoneNumber>?</inv:phoneNumber>
            <!--Optional:-->
            <inv:email>?</inv:email>
            <!--Optional:-->
            <inv:terminationDate>?</inv:terminationDate>
            <!--Optional:-->
            <inv:terminationDateStart>?</inv:terminationDateStart>
            <!--Optional:-->
            <inv:terminationDateEnd>?</inv:terminationDateEnd>
            <!--Optional:-->
            <inv:customFields>
               <!--Zero or more repetitions:-->
               <inv:customField>
                  <!--Optional:-->
                  <inv:id>?</inv:id>
                  <inv:name>?</inv:name>
                  <inv:value>?</inv:value>
                  <!--Optional:-->
                  <inv:fieldType>?</inv:fieldType>
                  <!--Optional:-->
                  <inv:required>?</inv:required>
               </inv:customField>
            </inv:customFields>
            <!--Optional:-->
            <inv:reportsTo>?</inv:reportsTo>
            <!--Optional:-->
            <inv:ccRights>
               <!--Zero or more repetitions:-->
               <inv:costCenterNo>?</inv:costCenterNo>
            </inv:ccRights>
            <!--Optional:-->
            <inv:title>?</inv:title>
         </inv:employee>
      </inv:AddEmployeeRequest>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
   <soapenv:Header/>
   <soapenv:Body>
      <inv:AddEmployeeResponse>
         <!--Optional:-->
         <inv:employeeID>?</inv:employeeID>
         <inv:result>
            <!--You may enter the following 2 items in any order-->
            <inv:code>?</inv:code>
            <!--Optional:-->
            <inv:message>?</inv:message>
         </inv:result>
      </inv:AddEmployeeResponse>
   </soapenv:Body>
</soapenv:Envelope>

Notes:

  • Inside the provided employee object, employeeID and status fields must always be provided.
  • It is possible to have required custom fields, in which case values for these fields must be provided;
  • The following elements accept only particular values:
    • employeeID – a non existing EIN;
    • status – 0 (active), 1 (inactive), 2 (terminated);
    • terminationDate – a mm/dd/yyyy string representation of a valid date;
    • email – a string representing an email address.
    • reportsTo – a valid EIN of an existing Active employee.
    • ccRights – valid Cost Center numbers
  • If the value of a custom field of boolean type is not provided, it will default to false;
  • If the value of a custom field of integer type is not provided, it will default to zero (0);
  • If the value of a custom field of double type is not provided, it will default to zero (0);
  • The value of a boolean custom field is specified as 0 (false) or 1 (true);

Errors:

  • Message validation error - SOAP fault message (see dedicated section for more details);
  • Data validation error – situations:
    • employeeID is not provided (as it is considered compulsory).
    • status is not provided (as it is considered compulsory).
    • there is already an employee with the provided employeeID;
    • if terminationDate is provided and the provided status is not 2 (terminated);
    • if the provided status is 2 (terminated) and the terminationDate is not provided;
    • if provided, costCenterNo must exist in the system (must be a valid one);
    • one of the particular fields (status, terminationDate, email, reportsTo, ccRights) contains invalid data;
    • a custom field contains an invalid value – an option that does not exist fora combo type one, a string represented different from mm/dd/yyyy for a date one, a string that does not represent an integer for an integer one, a string that does not represent a double for a double one, a string different from 0 or 1 for a Boolean one;
    • a custom field that is required is not provided;
    • a custom field does not exist for the provided employee;
  • Operation error, if a database error occurs.

editEmployee()

The method edits an existing employee using the provided fields from EmployeeDetails object. The result of the operation is an object represented by a code and a message that provides details about the success of the operation. The structure of the used objects may be observed in the appendix section of this document. The format of the request and response messages is the following:

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
   <soapenv:Header/>
   <soapenv:Body>
      <inv:EditEmployeeRequest>
         <inv:employee>
            <!--You may enter the following 15 items in any order-->
            <!--Optional:-->
            <inv:employeeID>?</inv:employeeID>
            <!--Optional:-->
            <inv:firstName>?</inv:firstName>
            <!--Optional:-->
            <inv:middleInitial>?</inv:middleInitial>
            <!--Optional:-->
            <inv:lastName>?</inv:lastName>
            <!--Optional:-->
            <inv:status>?</inv:status>
            <!--Optional:-->
            <inv:costCenterNo>?</inv:costCenterNo>
            <!--Optional:-->
            <inv:phoneNumber>?</inv:phoneNumber>
            <!--Optional:-->
            <inv:email>?</inv:email>
            <!--Optional:-->
            <inv:terminationDate>?</inv:terminationDate>
            <!--Optional:-->
            <inv:terminationDateStart>?</inv:terminationDateStart>
            <!--Optional:-->
            <inv:terminationDateEnd>?</inv:terminationDateEnd>
            <!--Optional:-->
            <inv:customFields>
               <!--Zero or more repetitions:-->
               <inv:customField>
                  <!--Optional:-->
                  <inv:id>?</inv:id>
                  <inv:name>?</inv:name>
                  <inv:value>?</inv:value>
                  <!--Optional:-->
                  <inv:fieldType>?</inv:fieldType>
                  <!--Optional:-->
                  <inv:required>?</inv:required>
               </inv:customField>
            </inv:customFields>
            <!--Optional:-->
            <inv:reportsTo>?</inv:reportsTo>
            <!--Optional:-->
            <inv:ccRights>
               <!--Zero or more repetitions:-->
               <inv:costCenterNo>?</inv:costCenterNo>
            </inv:ccRights>
            <!--Optional:-->
            <inv:title>?</inv:title>
         </inv:employee>
      </inv:EditEmployeeRequest>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
   <soapenv:Header/>
   <soapenv:Body>
      <inv:EditEmployeeResponse>
         <inv:result>
            <!--You may enter the following 2 items in any order-->
            <inv:code>?</inv:code>
            <!--Optional:-->
            <inv:message>?</inv:message>
         </inv:result>
      </inv:EditEmployeeResponse>
   </soapenv:Body>
</soapenv:Envelope>

Notes:

  • Inside the provided employee object, employeeID fields must always be provided.
  • The following elements accept only particular values:
    • employeeID – an existing EIN;
    • status – 0 (active), 1 (inactive), 2 (terminated);
    • terminationDate – a mm/dd/yyyy string representation of a valid date;
    • email – a string representing an email address.
    • reportsTo – a valid EIN of an existing Active employee.
    • ccRights – valid Cost Center numbers
  • If the value of a custom field of boolean type is not provided, it will default to false;
  • If the value of a custom field of integer type is not provided, it will default to zero (0);
  • If the value of a custom field of double type is not provided, it will default to zero (0);
  • The value of a boolean custom field is specified as 0 (false) or 1 (true);

Errors:

  • Message validation error - SOAP fault message (see dedicated section for more details);
  • Data validation error – situations:
  • there is no employee with the provided employeeID;
    • if terminationDate is provided and either a non 2 (terminated) status is provided or the employee that is edited has a non 2 (terminated) status;
    • if the provided status is 2 (terminated) and the terminationDate is notprovided;
    • if provided, costCenterNo must exist in the system (must be a valid one);
    • one of the particular fields _(status, terminationDate, email, reportsTo,ccRights) _contains invalid data;
    • a custom field contains an invalid value – an option that does not exist for a combo type one, a string represented different from mm/dd/yyyy for a date one, a string that does not represent an integer for an integer one, a string that does not represent a double for a double one, a string different from 0 or 1 for a Boolean one;
    • a custom field does not exist for the provided employee;
  • Operation error, if a database error occurs.

findEmployee()

The method queries the database for employees using as filter the elements provided in the EmployeeDetails object. Together with the filter, a maximum number of returned items may be included in the request. If this is not present, all found records are returned from the database. The result of the operation is a list with zero or more employees that match the provided filter and an object represented by a code and a message with details about the success of the operation. The structure of the used objects may be observed in appendix section of this document. The format of the request and response messages is the following:

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
   <soapenv:Header/>
   <soapenv:Body>
      <inv:FindEmployeeRequest>
         <inv:employee>
            <!--You may enter the following 15 items in any order-->
            <!--Optional:-->
            <inv:employeeID>?</inv:employeeID>
            <!--Optional:-->
            <inv:firstName>?</inv:firstName>
            <!--Optional:-->
            <inv:middleInitial>?</inv:middleInitial>
            <!--Optional:-->
            <inv:lastName>?</inv:lastName>
            <!--Optional:-->
            <inv:status>?</inv:status>
            <!--Optional:-->
            <inv:costCenterNo>?</inv:costCenterNo>
            <!--Optional:-->
            <inv:phoneNumber>?</inv:phoneNumber>
            <!--Optional:-->
            <inv:email>?</inv:email>
            <!--Optional:-->
            <inv:terminationDate>?</inv:terminationDate>
            <!--Optional:-->
            <inv:terminationDateStart>?</inv:terminationDateStart>
            <!--Optional:-->
            <inv:terminationDateEnd>?</inv:terminationDateEnd>
            <!--Optional:-->
            <inv:customFields>
               <!--Zero or more repetitions:-->
               <inv:customField>
                  <!--Optional:-->
                  <inv:id>?</inv:id>
                  <inv:name>?</inv:name>
                  <inv:value>?</inv:value>
                  <!--Optional:-->
                  <inv:fieldType>?</inv:fieldType>
                  <!--Optional:-->
                  <inv:required>?</inv:required>
               </inv:customField>
            </inv:customFields>
            <!--Optional:-->
            <inv:reportsTo>?</inv:reportsTo>
            <!--Optional:-->
            <inv:ccRights>
               <!--Zero or more repetitions:-->
               <inv:costCenterNo>?</inv:costCenterNo>
            </inv:ccRights>
            <!--Optional:-->
            <inv:title>?</inv:title>
         </inv:employee>
         <!--Optional:-->
         <inv:maxNoOfRecords>?</inv:maxNoOfRecords>
      </inv:FindEmployeeRequest>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
   <soapenv:Header/>
   <soapenv:Body>
      <inv:FindEmployeeResponse>
         <!--Zero or more repetitions:-->
         <inv:employee>
            <!--You may enter the following 15 items in any order-->
            <!--Optional:-->
            <inv:employeeID>?</inv:employeeID>
            <!--Optional:-->
            <inv:firstName>?</inv:firstName>
            <!--Optional:-->
            <inv:middleInitial>?</inv:middleInitial>
            <!--Optional:-->
            <inv:lastName>?</inv:lastName>
            <!--Optional:-->
            <inv:status>?</inv:status>
            <!--Optional:-->
            <inv:costCenterNo>?</inv:costCenterNo>
            <!--Optional:-->
            <inv:phoneNumber>?</inv:phoneNumber>
            <!--Optional:-->
            <inv:email>?</inv:email>
            <!--Optional:-->
            <inv:terminationDate>?</inv:terminationDate>
            <!--Optional:-->
            <inv:terminationDateStart>?</inv:terminationDateStart>
            <!--Optional:-->
            <inv:terminationDateEnd>?</inv:terminationDateEnd>
            <!--Optional:-->
            <inv:customFields>
               <!--Zero or more repetitions:-->
               <inv:customField>
                  <!--Optional:-->
                  <inv:id>?</inv:id>
                  <inv:name>?</inv:name>
                  <inv:value>?</inv:value>
                  <!--Optional:-->
                  <inv:fieldType>?</inv:fieldType>
                  <!--Optional:-->
                  <inv:required>?</inv:required>
               </inv:customField>
            </inv:customFields>
            <!--Optional:-->
            <inv:reportsTo>?</inv:reportsTo>
            <!--Optional:-->
            <inv:ccRights>
               <!--Zero or more repetitions:-->
               <inv:costCenterNo>?</inv:costCenterNo>
            </inv:ccRights>
            <!--Optional:-->
            <inv:title>?</inv:title>
         </inv:employee>
         <inv:result>
            <!--You may enter the following 2 items in any order-->
            <inv:code>?</inv:code>
            <!--Optional:-->
            <inv:message>?</inv:message>
         </inv:result>
      </inv:FindEmployeeResponse>
   </soapenv:Body>
</soapenv:Envelope>

Notes:

  • A search filter may contain both standard and custom fields. Inside the EmployeeDetails object, terminationDate is ignored even if it is set terminationDateStart and terminationDateEnd are used instead;
  • The following elements accept only particular values:
    • status – 0 (active), 1 (inactive), 2 (terminated);
    • terminationDateStart, terminationDateEnd – a mm/dd/yyyy string representation of a valid date;
    • email – a string representing an email address.
    • ccRights – at most one existing cost center in the application
  • The value of a boolean custom field is specified as 0 (false) or 1 (true);

Errors:

  • Message validation error - SOAP fault message (see dedicated section for more details);
  • Data validation error – situations:
    • one of the particular fields _(status, terminationDateSart, terminationDateEnd, email) _contains invalid data;
    • a custom field contains an invalid value – an option that does not exist for a combo type one, a string represented different from mm/dd/yyyy for a date one, a string that does not represent an integer for an integer one, a string that does not represent a double for a double one, a string different from 0 or 1 for a Boolean one;
    • a custom field does not exist for the queried service type;
  • Operation error, if a database error occurs.

Reviews